Skip to main content

SpacemiT debug upstream

Follow our Philosophy: "Take from Open Source, Contribute Back to Open Source", we are deeply committed to the "Upstream First" principle in our development and maintenance of debug software. This means we proactively contribute all our optimizations and fixes back to the original open-source projects. We collaborate with the global developer community to drive the growth and success of the RISC-V ecosystem.

The core open-source software for RISC-V debugging consists primarily of GDB and OpenOCD.

  • GDB (GNU Debugger) is a powerful source-level debugging tool. In the RISC-V ecosystem, GDB continues to serve as the primary interactive interface for developers during debug.
  • OpenOCD (Open On-Chip Debugger) provides the actual implementation of the RISC-V Debug Specification. The community maintains a dedicated RISC-V–adapted fork, available at: https://github.com/riscv-collab/riscv-openocd 1 The riscv-openocd fork currently supports RISC-V Debug Spec v0.11 and v0.13, and includes partial support for v1.0. This is sufficient for everyday development and debugging, and the project continues to evolve. The riscv-test repository (https://github.com/riscv-software-src/riscv-tests) includes a Debug Tests suite. Because debugging depends on the coordination of several system components, this test suite uses Python scripts to call both OpenOCD and GDB, simulating a real end-to-end debug flow. This approach helps identify issues across the entire debug path—from the debug interface to underlying low-level components.

Starting with K1: The Upstream Journey of a PR​

When we were building SpacemiT’s first RISC-V AI CPU — the K1, tools like OpenOCD and riscv-tests were essential for debugging and validation. But the K1 brought a unique challenge. Its hardware splits 8 cores into two clusters, each with its own Debug Module (DM), while both DMs share a single Debug Transport Module (DTM). At the time, neither open-source OpenOCD nor commercial debuggers supported this kind of “one DTM, multiple DMs” setup. 2 Because OpenOCD is open source, we could dig into the code ourselves. After studying the design, we realized we could reuse logic from other architectures. In the end, it only took six lines of code to make multi-DM support work. After verifying the fix on FPGA, we sent an upstream PR with 27 lines of changes. 3 That PR kicked off a long but rewarding process. Maintainers gave great feedback, and after 126 review rounds, the final merged version expanded to 396 lines. The update didn’t just add multi-DM support—it also improved checks, refreshed documentation, and refactored part of the DM interface to make the code cleaner and easier to maintain. 4 Although no one expected a “6-line fix” to expand into a large-scale refactor, the process significantly deepened the team’s understanding of the code. It also reduced long-term maintenance costs and contributed meaningful improvements to the open-source ecosystem—a worthwhile investment. Throughout the collaboration, the open and cooperative atmosphere of the community strengthened SpacemiT’s commitment to contributing improvements upstream. The goal is to “do it right from the beginning” instead of maintaining a patched downstream fork and constantly dealing with version conflicts.

From K1 to K3: Continuous Investment in Upstream Development​

After completing debug support for the K1, all related configuration files were merged into the OpenOCD mainline. Today, developers can debug the K1 directly with upstream OpenOCD — no patches required. 5 Beyond the issues discovered and fixed during the K1 cycle, new needs and challenges surfaced during the development of our next-generation chip, K3. For example:

  • The K3 uses the X100 core, which supports virtualization extensions. While debugging virtual machines, we identified a potential flaw in OpenOCD’s address-translation logic.
  • New features introduced in Debug Spec v1.0, such as External Trigger, also required fresh updates to the codebase. After locating and fixing these issues, SpacemiT pushed all improvements back to the community. When K3 is officially released, developers will be able to debug it just like the K1 — using the upstream version out of the box, with a smooth and reliable debugging experience.

Looking Ahead​

So far, SpacemiT has contributed 40+ commits to OpenOCD and riscv-tests, with several additional patches still under review. We want to express our thanks to the community developers — especially the maintainers @timsifive, @en-sc, and @JanMatCodasip — for their support throughout code reviews and collaboration.

The RISC-V Debug Specification v1.0 was officially approved in February 2025. Work on improving riscv-openocd continues, and upstream OpenOCD is actively merging updates from the RISC-V fork. As the RISC-V ecosystem grows, CPU cores, SoCs, and the software stack are becoming more complex — making robust and efficient debugging more important than ever. With RISC-V’s openness and flexibility as the foundation, SpacemiT will continue working closely with the community, contributing to the open-source toolchain, and helping push the RISC-V ecosystem forward.